Learning objectives
What you will be able to do
By the end of this module you can operate confidently across the full Domain Owner lifecycle — from first commit to ship gate.
📂
Write and maintain all three domain files
Produce a complete business-rules.md, glossary.md, and personas.md from scratch and keep them current across sprints.
🔍
Review and approve a spec with confidence
Identify business logic errors in an AI-generated spec and make the correct approve / return / escalate decision.
✅
Execute a P0 AC walk correctly
Complete a manual acceptance criteria walk-through, distinguish logic failures from technical defects, and check off acceptance-criteria.md.
🚀
Contribute to roadmap and own the ship gate
Write a clear backlog problem statement, frame priority in business terms, and execute the ship gate sign-off correctly.
Owning docs/domain/
Your domain files are the primary source of truth that AI agents read before drafting specs. Understanding what goes in each file — and when to update them — is the foundation of everything else in this module.
Lesson 2.1 · The three files you own
What goes in each file and why it matters
The docs/domain/ directory is not a formality. The product-domain-expert agent reads these files every time it generates a spec. The quality of every spec — and therefore the quality of every feature — is directly determined by the quality of what you write here. Think of these files as the instructions you give to a brilliant but literal-minded contractor: they will follow exactly what is written, no more and no less.
Contains every constraint and logic rule the system must enforce because the business requires it — not because of technical preference. If a rule is not here, the agent will not know to enforce it.
- Rule IDUnique identifier (e.g. BR-042) so rules can be referenced in specs and ACs without ambiguity.
- ConditionThe precise trigger or situation when the rule applies. Be as specific as possible — avoid "usually" or "sometimes".
- BehaviourWhat the system must do when the condition is met. Use "must", "must not", "shall" — not "should" or "may".
- RationaleWhy this rule exists (regulatory, contractual, operational). Helps agents avoid contradicting the rule in adjacent features.
- SourceWhere the rule came from — a regulation, a stakeholder decision, a past incident. Enables future review and challenge.
A single source of truth for what every domain term means. When "settlement" means different things to different people, bugs follow. The glossary eliminates that ambiguity so AI-generated specs use consistent, correct language.
- TermThe exact string used in specs and ACs — capitalisation matters.
- DefinitionA precise, one-sentence definition a non-expert could use. Avoid circular definitions.
- AliasesOther words used for the same thing (by different teams, systems, or documents). Agents need to recognise all of them.
- ContrastTerms that are commonly confused with this one — and how to tell them apart. This prevents the most frequent AC errors.
Grounds every spec in real user reality. Without personas, AI agents generate features for a generic "user" who does not exist. With personas, generated ACs reflect how actual people behave, what they expect, and what would break their workflow.
- Name & roleA realistic name and job title. Not "User A" — specificity forces the agent to think concretely.
- GoalsWhat this person is trying to achieve in their job — not in the app. The job-level goal drives which features matter.
- Mental modelHow they think the system works, even if it is different from how it actually works. AC must account for their expectations.
- Pain pointsWhat frustrates them today. Specs that solve the wrong pain point pass all ACs but fail the user.
- Edge behavioursUnusual but real things this persona does that could break a naïve implementation. These belong in P1 ACs.
Lesson 2.2 · The update cadence rule
Always update docs/domain/ before editing any spec
This rule sounds simple but it encodes an important discipline. Every time you are about to touch a spec, you must first ask: "Has anything changed about the business that I have not yet written down?" If the answer is yes — even slightly — update the domain files first.
⚠️
Why this order matters
If you update the spec directly without updating the domain file, the domain files become stale. The next time an agent reads them to generate a related spec, it will use the old, incorrect rules — and produce a spec that contradicts the one you just manually corrected. You will spend sprint after sprint patching AI output that is working from outdated instructions.
💡
Something new becomes clear about the domain
A stakeholder clarifies a rule. A regulatory change lands. A past incident reveals an edge case. A user interview surfaces an unexpected behaviour.
✏️
Write it into the correct domain file first
Add the business rule to business-rules.md, define the new term in glossary.md, or update the relevant persona in personas.md. Do not touch the spec yet.
🔍
Now open the spec and apply the change
With the domain file updated, you can now edit the spec knowing the source of truth is consistent. The agent will pick up the correct rule on its next generation cycle.
📢
Flag related specs that may also be affected
A change in a business rule often affects more than one feature. Scan for other specs that reference the same rule or persona and mark them for review.
✅
Lab exercise
Open the current business-rules.md in your squad's repository. Identify one rule that is missing, one that is ambiguous, and one that is out of date. Write the corrected version for each, using the field structure from Lesson 2.1. Time: 20 minutes.
Spec Review & Approval
The spec is the contract between the business and the build. Your approval is the business signature. This section explains how to review with the right lens and how to make the approve / return / escalate decision correctly every time.
Lesson 2.3 · Reading a spec with a business lens
How to review an AI-generated spec.md
When an AI generates a spec, it is doing its best with the domain files you gave it. Your job as reviewer is not to evaluate the writing quality or the technical approach — it is to ask: "Does this spec correctly represent what the business needs, in a way a competent engineer could implement correctly?"
There are three layers to check. Move through them in order. Do not jump to layer 3 if you have not resolved layer 1.
| Layer |
What to check |
Common failure modes |
| 1 · Scope integrity |
Does the spec build exactly what was intended — no more, no less? Are any features implied but not discussed? |
Spec drifts into adjacent features. Scope is technically accurate but misses the real stakeholder intent. |
| 2 · Business rule coverage |
Is every relevant business rule from business-rules.md reflected in the spec? Are any rules contradicted? |
Agent omits a rule because it was not in the domain file. Agent partially applies a rule. Two rules in tension were not reconciled. |
| 3 · AC correctness |
Is each acceptance criterion measurable, unambiguous, and testable? Does it reflect actual user behaviour from personas.md? |
ACs use vague language ("should work correctly"). ACs describe implementation rather than outcome. Edge cases from personas are absent. |
💡
The "stranger test" for AC
Read each AC aloud and ask: could a competent developer who has never spoken to anyone on this project implement this correctly from this sentence alone? If the answer is no — the AC is not ready. Rewrite it before approving.
Lesson 2.4 · The approve / return / escalate decision
When to approve, when to send back, when to escalate
After reviewing the three layers, you make one of three decisions. Each has a specific meaning and triggers a specific workflow. Using the wrong decision wastes a cycle. Approving something that should have been returned introduces a defect that will cost more to fix later.
✅
Approve
All three layers pass. Set status: approved. Build begins.
↩️
Return
Specific, fixable business issues found. Annotate the spec. Agent re-drafts.
🚨
Escalate
Fundamental ambiguity or stakeholder conflict. Requires human resolution before speccing continues.
| Situation |
Correct decision |
What to do |
| One AC uses vague language but intent is clear |
Return |
Rewrite the AC yourself in the spec comment. Agent updates and re-submits. |
| A business rule is missing from two ACs |
Return |
Update business-rules.md first, then annotate which ACs need the rule applied. Return to agent. |
| Spec is well-written but scope has expanded beyond what was agreed |
Return |
Explicitly mark the out-of-scope items. Document scope decision in business-rules.md rationale. |
| Two stakeholders have given contradictory requirements |
Escalate |
Surface the conflict to both stakeholders. Do not approve or return until resolved. Document the resolution. |
| All three review layers pass |
Approve |
Set status: approved in spec.md. This is your binding commitment that the business requirements are correct. |
🔑
What status: approved commits you to
When you set status to approved, you are making a professional commitment that: the scope is correct, the business rules are reflected, and the ACs correctly define done from a business perspective. If a defect is later found that traces back to an approved spec, the root cause is the approval — not the build. Approve only when all three layers are genuinely satisfied.
✅
Lab exercise
Review the sample spec in your squad's examples/ folder. Work through all three review layers. Write your decision (approve / return / escalate) and provide at least two specific annotations. Compare your decision with a colleague. Time: 25 minutes.
P0 AC Validation
The test phase is where you confirm — not discover — that the feature meets its business requirements. If you did your job well in governance, this is a structured walk, not a search for surprises.
Lesson 2.5 · What a P0 AC walk actually means
Walking acceptance criteria — not running scripts, not spot-checking
"Manually walk each P0 AC" is a specific instruction. It does not mean running automated tests. It does not mean clicking around the UI until it feels right. It means: take the exact text of each P0 acceptance criterion and verify, step by step, that the system satisfies it exactly as written.
The walk is confirmatory. By Phase 5, you already know what the system should do — you wrote or approved the AC. The walk answers: does it actually do that? Every P0 AC must be checked individually and the result recorded in acceptance-criteria.md.
🔶
Common mistakes in AC validation
Checking "the feature works" without reading the AC text. Relying on the automated test result to infer the AC is met. Skipping edge case ACs because the happy path passed. Confusing a P1 failure with a P0 failure. Any of these result in a ship gate sign-off that does not actually confirm what it claims to confirm.
Below is an example of what a correctly completed acceptance-criteria.md walk looks like. Click each checkbox to mark it as verified — this mirrors the real workflow.
P0
When a trader submits an FX trade, a confirmation message must be sent within 120 seconds of execution timestamp.
Walk: submit a test trade → observe confirmation timestamp → verify delta ≤ 120s
P0
Trades above $10,000,000 USD notional must require dual authorisation before confirmation is sent.
Walk: submit a $10.5M trade → verify authorisation prompt appears → confirm second approver flow completes before confirmation
P0
If the confirmation cannot be delivered within 120 seconds, the system must log a confirmation failure event and alert the operations team.
Walk: simulate delivery failure → verify failure event appears in ops log → verify alert is triggered
P0
Confirmation messages must include: trade ID, currency pair, notional amount, rate, execution timestamp, and counterparty name.
Walk: inspect confirmation content field by field — all six required fields must be present and correctly populated
P1
Traders must be able to retrieve any confirmation issued in the last 90 days from the confirmation history screen.
Walk: navigate to history → search for a trade from 89 days ago → verify confirmation is retrievable
Lesson 2.6 · Distinguishing failures and escalating correctly
Business logic failure vs technical defect — and what to do with each
During a P0 walk you will occasionally find that an AC is not satisfied. Before escalating, you need to classify the failure correctly — because the two types route to different people.
| Failure type |
Definition |
Who resolves it |
Examples |
| Business logic failure |
The system does something technically functional but wrong from a business perspective — the AC intent was misunderstood. |
Domain Owner diagnoses; Domain Owner and AI Engineer fix together |
Timeout fires at 90s instead of 120s. Dual auth threshold is $1M instead of $10M. Confirmation omits counterparty name. |
| Technical defect |
The system attempts to satisfy the AC correctly but fails due to a technical error — the AC intent was understood but implementation is broken. |
AI Engineer diagnoses and resolves |
Confirmation service crashes under load. Timestamp field is null due to a race condition. Database query returns wrong row. |
| AC ambiguity |
The AC can be interpreted in two ways — the system satisfies one interpretation but not the other. Neither reading is clearly correct. |
Domain Owner must rewrite the AC — then reassess the implementation |
"Confirmation must be sent promptly" (no time specified). "All required fields" (list not defined). "Appropriate alert" (no recipient defined). |
Scenario — Business logic failure
"The confirmation is sent in 85 seconds consistently, but the AC says 120 seconds — yet the reviewer flagged this as a pass because 85 < 120."
Correct. The AC defines a maximum, not a target. 85 seconds satisfies the AC. If your intent was "exactly 120 seconds", the AC was wrong. Update the AC, not the code.
Scenario — AC ambiguity
"The AC says 'the operations team must be alerted' but it does not specify via what channel. The implementation sends an email. Is this a pass?"
Ambiguous AC. Rewrite it to specify the channel (email, Slack, PagerDuty). Once rewritten, assess whether the email implementation satisfies the new AC. Do not pass or fail the original.
Roadmap Input & the Ship Gate
The Domain Owner shapes what gets built and decides when it is ready to ship. This section covers the upstream contribution (backlog & priority) and the downstream commitment (ship gate sign-off).
Lesson 2.7 · Contributing to the roadmap
What Domain Owner input looks like — and what it does not look like
At Phase 1, you contribute to the backlog by writing or reviewing problem statements and framing priority. Your input is about business value and urgency. It is not about effort estimates, technical feasibility, or sprint capacity — those belong to the AI Engineer.
| Input type |
Domain Owner? |
What good input looks like |
| Problem statement |
✓ Yes |
"Traders are manually reconciling confirmation failures every morning. This takes 45 minutes daily and introduces error risk. We need automated detection and alerting." |
| Business priority / urgency |
✓ Yes |
"This is P0 for Q2 because the regulator audit is in March. Missing it has a compliance risk, not just a quality risk." |
| Scope boundaries |
✓ Yes |
"In scope: detection and ops alerting. Out of scope: auto-remediation. We need ops to review before any automatic fix runs." |
| Effort estimate / story points |
✗ No |
This belongs to the AI Engineer. Your input here is noise, not signal. |
| Technical approach |
✗ No |
How it is built is not your input to give. State the desired outcome, not the implementation. |
| Sprint capacity decisions |
✗ No |
The AI Engineer manages agent capacity. You provide priority ordering, not slot allocation. |
💡
Writing a strong problem statement
The best problem statements have four parts: (1) who experiences the problem, (2) what the problem is in concrete terms, (3) the consequence of not solving it, and (4) how we will know it is solved. A problem statement that covers all four gives the product-domain-expert agent everything it needs to generate a high-quality spec on the first pass.
Lesson 2.8 · The ship gate
What "all P0 ACs ✓" sign-off actually commits you to
The ship gate has two independent requirements — both must be satisfied before a feature ships. The AI Engineer's gate is technical: all automated tests green. Your gate is business: all P0 ACs manually verified and checked off. Neither gate can substitute for the other.
When you sign off on the ship gate, you are making a public, recorded commitment that: every P0 AC has been personally walked and verified; no P0 AC has a passing check that was done by inference rather than direct observation; any ambiguous AC discovered during the walk has been resolved and re-verified. A ship gate sign-off that does not meet these conditions is a false approval — and the risk lands on you.
🔶
Signs you are about to sign off incorrectly
"The automated tests cover this AC, so I'll count it as verified." — Do not. Walk it. "I checked this AC two weeks ago during a demo." — That was a different build. Walk it again. "Only three of five P0 ACs are done but we're under time pressure." — Incomplete P0 validation is a blocked ship gate. No exceptions.
After the ship gate passes, you review the 3-bullet release summary before archiving. This summary must accurately reflect what was delivered. If it does not, correct it — a wrong release summary corrupts the squad's institutional memory and can cause future agents to make incorrect assumptions about what the system already does.
✅
What a correct 3-bullet release summary looks like
• What shipped: FX trade confirmation service with automated delivery and dual-auth enforcement above $10M notional.
• What was descoped: Auto-remediation of failed confirmations — deferred to Q3 per stakeholder agreement on 14 Feb.
• Known limitation: Confirmation history retrieval currently limited to 90 days; extension requires DB index change, tracked in backlog item #447.
Knowledge check
Test your understanding across all four topics
1. You have just learned that a new regulatory rule requires FX trades above $5M to be flagged for compliance review. Where do you record this first?
ADirectly in the next spec.md that touches trade submission
BIn business-rules.md first, then apply the rule in the relevant spec
CIn a Slack message to the AI Engineer so they can add it to the build
DIn personas.md under the compliance officer persona
2. The glossary.md defines "Settlement" as T+2. A new spec uses "Settlement" to mean T+0. What should you do?
AApprove the spec — the context makes the meaning clear
BUpdate the spec to say T+2, since that is the glossary definition
CFirst decide whether the business intent is T+0 or T+2, update glossary.md if needed (or add a new term), then align the spec
DReturn the spec to the agent and ask it to resolve the conflict
3. During spec review, you find that the AC for a dual-authorisation flow says "the second approver must confirm the trade". The word "confirm" is not in the glossary and could mean two different actions in your system. What is the correct decision?
AApprove — the developer will figure out which action is intended
BReturn — rewrite the AC to use an unambiguous term, and add the correct definition to the glossary
CEscalate — this is a stakeholder conflict requiring external resolution
DApprove with a comment — comments in specs are binding instructions to the agent
4. You are reviewing a spec and find that two business rules from business-rules.md appear to contradict each other in the context of this feature. What do you do?
AReturn the spec and ask the agent to resolve the contradiction
BApply the most recently added rule and return the spec
CEscalate — a contradiction between business rules requires human resolution before the spec can be correct
DApprove the spec noting the contradiction — the AI Engineer can decide which rule takes precedence
5. During your P0 AC walk, automated tests show 100% pass for all P0 ACs. Do you still need to walk them manually?
ANo — 100% test pass is sufficient evidence that P0 ACs are met
BYes — automated tests verify code behaviour, not business intent. The manual walk verifies that each AC correctly represents what the business needs.
COnly if the AI Engineer requests it
DOnly for P0 ACs that touch external systems
6. During a P0 AC walk you find that the system sends confirmation in 85 seconds, but the AC states "within 120 seconds". The AC has been approved. How do you record this?
AFail — the system is not meeting the target of 120 seconds
BPass — 85 seconds satisfies "within 120 seconds". Record it as verified.
CPartial pass — the system is faster than required, which may indicate a different implementation than intended
DEscalate — a discrepancy between observed behaviour and AC value must be reviewed
7. When contributing to the roadmap, a colleague asks you to estimate how many sprints it will take to implement the confirmation service. What do you do?
AProvide your best estimate based on past experience
CRedirect — effort estimates belong to the AI Engineer. Your contribution is the business priority and urgency framing.
BCollaborate with the AI Engineer to produce a joint estimate
DDecline to estimate and wait for the AI Engineer to provide one before contributing priority input
8. Four of five P0 ACs have been verified. The team is under deadline pressure to ship. Can you sign off the ship gate?
AYes — 80% completion is within acceptable tolerance for a first release
BYes — if the unverified AC is low-risk, the business benefit of shipping outweighs the risk
CYes — with a documented exception approved by the stakeholder
DNo — incomplete P0 validation is a blocked ship gate. All P0 ACs must be verified before sign-off.
Module 02 — Key takeaways
- Domain files are the instructions you give agents. Their quality directly determines the quality of every spec generated. Keep them current, structured, and unambiguous.
- Always update
docs/domain/ before editing a spec — not after. The order is non-negotiable.
- Spec approval is a three-layer review: scope integrity, business rule coverage, AC correctness. Approve only when all three pass.
- Setting
status: approved is a professional commitment — not an administrative action. The defects that trace back to an approved spec are your responsibility.
- A P0 AC walk is a direct, step-by-step verification of each criterion. Automated test results, demos, and past observations do not substitute for it.
- Business logic failures route to you. Technical defects route to the AI Engineer. AC ambiguity requires you to rewrite the AC before routing anything.
- Your roadmap contribution is business value and urgency — not effort, not approach, not capacity. Stay in your lane and your input will be higher quality.
- The ship gate requires all P0 ACs verified. No exceptions. No partial sign-offs. Incomplete validation blocks the gate.